ParcelLabel API

How to generate parcel labels for parcels being sent from overseas locations

When generating parcel labels for packages originating from outside of New Zealand, merchants are able to choose the shipping method for how the parcel will be delivered to its destination. NZ Post currently offers the following services for customers:

• International Courier (tracked) - courier service into New Zealand
• ETOE (Please speak to your NZ Post account manager). Refer to the Create Label(s) - International ETOE page

These services need to be enabled by NZ Post before a merchant can use the service. Please contact your NZ Post account manager to activate the service you require.

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

A unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a consignment (for International Courier only)

Request Parameters

For each of these services, the parameter requirements are similar but each service has slightly different requirements and needs to use the relevant service code. In the following table, we have provided which fields are required in the label request for a particular service. Additional requirements for Courier Tracked services are listed beneath the standard parameters.

Code samples for each of these separate service types are displayed further down this page.

Courier Base Services

The following are sample base service codes for International inbound parcel and satchel courier services

Return Base Services

The following are sample base service codes for International Economy Returns and Courier Returns services

Courier Satchel Sizes

Where the parcel is a satchel (and you intend to send as a satchel), and the service code has not been selected via the ShippingOptions API, then the envelope size must be concatenated to the end of the service code before submitting the label request e.g. IWOLTPSFS

Below is a list of valid satchel sizes.

Courier Add ons

The following are sample value add-ons.

Courier Add-on Rules

The following rules apply to add-on services included in a label request:

1. Add-on services can only be present when the carrier is CourierPost
2. Only one of the following can be present on the label request: IWXOLRD Courier Rural Delivery, IWXOLSAT Courier Saturday Delivery, or IWXOLDG Courier Dangerous Goods
3. Signature required, IWXSR, may always be present

Merchants must ensure that when appropriate, the prepaid ticket corresponding to the requested add-on service is affixed to the parcel.

Example 1: Overnight CourierPost Outbound label for a single parcel (174x100mm)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "Order 34234",
    "sender_reference_2": "Sales",
    "label_dimensions" : "174x100",
    "paper_dimensions": {
    "width_cm": 17.4,
    "height_cm": 10.0
  },
    "sender_details": {
        "name": "Daisy Duck",
        "phone": "0211246987",
        "site_code": 34533
    },
    "pickup_address": {
        "country_code": "NZ",
        "company_name": "Cartoon Company",
        "street": "122 Kerwyn Avenue",
        "suburb": "East Tamaki",
        "city": "Auckland",
        "postcode": "2013"
    },
    "receiver_details": {
        "name": "Mickey Mouse",
        "phone": "0224309792",
        "email": "m.mouse@abc.co.nz"
    },
    "delivery_address": {
        "company_name": "",
        "street_number": "",
        "street": "59 Tawa Road",
        "suburb": "One Tree Hill",
        "city": "Auckland",
        "state": "",
        "country_code": "NZ",
        "postcode": "1061",
        "instructions": "look out for dog"
    },
    "parcel_details": [
        {
            "service_code": "IWXOLP",
            "return_indicator": "OUTBOUND",
            "description": "Test description",
            "dimensions": {
                "length_cm": 50,
                "width_cm": 20,
                "height_cm": 20,
                "weight_kg": 1.7
            }
        }
    ]
}

```

Example 2: Overnight CourierPost Return for a single parcel (174x100mm)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "Order ABC1",
    "sender_reference_2": "Return",
    "label_dimensions" : "174x100",
    "paper_dimensions": {
    "width_cm": 17.4,
    "height_cm": 10.0
  },
    "sender_details": {
        "name": "Daisy Duck",
        "phone": "0211246987",
        "site_code": 34533
    },
    "pickup_address": {
        "country_code": "NZ",
        "company_name": "Cartoon Company",
        "street": "122 Kerwyn Avenue",
        "suburb": "East Tamaki",
        "city": "Auckland",
        "postcode": "2013"
    },
    "receiver_details": {
        "name": "Mickey Mouse",
        "phone": "0224309792",
        "email": "m.mouse@abc.co.nz"
    },
    "delivery_address": {
        "company_name": "",
        "street_number": "",
        "street": "59 Tawa Road",
        "suburb": "One Tree Hill",
        "city": "Auckland",
        "state": "",
        "country_code": "NZ",
        "postcode": "1061",
        "instructions": ""
    },
    "parcel_details": [
        {
            "service_code": "IWXROLP",
            "return_indicator": "RETURN",
            "description": "Test description",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 50,
                "width_cm": 20,
                "height_cm": 20,
                "weight_kg": 1.7
            },
            "parcel_contents": [{
                    "content_number": 1,
                    "description": "Holdem Purse  (limited edition)",
                    "quantity": 1,
                    "weight_kg": 0.3,
                    "value": 67.10,
                    "country_code": "NZ"
                }
            ]
        }
    ]
}

```

Example 3: Overnight CourierPost Outbound label and Overnight Return label (174x100mm)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "NZSEMKO",
    "sender_reference_2": "NZSEMKO",
    "label_dimensions": "174x100",
    "paper_dimensions": {
        "width_cm": 17.4,
        "height_cm": 10.0
    },
    "sender_details": {
        "name": ".",
        "phone": "6112345678",
        "email": "",
        "company_name": "",
        "site_code": 34533
    },
    "pickup_address": {
        "company_name": "D-CO LIMITED",
        "building_name": "",
        "unit_type": "",
        "unit_value": "",
        "floor": "",
        "street": "Private Bag 211111",
        "suburb": "Returns Centre",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2154"
    },
    "receiver_details": {
        "name": "John Smith",
        "phone": "0211632789",
        "email": ""
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "",
        "company_name": "",
        "unit_type": "",
        "unit_value": "",
        "floor": "",
        "street": "192C Cliff View Drive",
        "suburb": "Green Bay",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "0604",
        "instructions": ""
    },
    "parcel_details": [
        {
            "service_code": "IWXOLP",
            "add_ons": [],
            "return_indicator": "OUTBOUND",
            "description": "SALES",
            "dimensions": {
                "length_cm": 20,
                "width_cm": 20,
                "height_cm": 30,
                "weight_kg": 2
            }
        },
        {
            "service_code": "IWROLP",
            "add_ons": [],
            "return_indicator": "RETURN",
            "description": "RETURN",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 20,
                "width_cm": 20,
                "height_cm": 30,
                "weight_kg": 2
            },
            "parcel_contents": [
                {
                    "content_number": 1,
                    "description": "Holdem Purse  (limited edition)",
                    "quantity": 1,
                    "weight_kg": 0.3,
                    "value": 67.10,
                    "country_code": "NZ"
                }
            ]
        }
    ]
}

```

Example 4: Overnight CourierPost Outbound label and Economy Return label (150x100mm)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "NZ12345",
    "sender_reference_2": "NZ12345",
    "label_dimensions": "150x100",
    "paper_dimensions": {
        "width_cm": 15.0,
        "height_cm": 10.0
    },
    "sender_details": {
        "name": ".",
        "phone": "6112345678",
        "email": "",
        "company_name": "",
        "site_code": 34533
    },
    "pickup_address": {
        "company_name": "The Widget Company",
        "building_name": "",
        "unit_type": "",
        "unit_value": "",
        "floor": "",
        "street": "Private Bag 211111",
        "suburb": "Returns Centre",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2154"
    },
    "receiver_details": {
        "name": "Jane Doe",
        "phone": "0211632789",
        "email": ""
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "",
        "company_name": "",
        "unit_type": "",
        "unit_value": "",
        "floor": "",
        "street": "192C Cliff View Drive",
        "suburb": "Green Bay",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "0604",
        "instructions": ""
    },
    "parcel_details": [
        {
            "service_code": "IWXOLP",
            "add_ons": [
                "IWXSR"
            ],
            "return_indicator": "OUTBOUND",
            "description": "SALES",
            "dimensions": {
                "length_cm": 20,
                "width_cm": 20,
                "height_cm": 30,
                "weight_kg": 2
            }
        },
        {
            "service_code": "IWXEROLE",
            "add_ons": [],
            "return_indicator": "RETURN",
            "description": "RETURN",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 20,
                "width_cm": 20,
                "height_cm": 30,
                "weight_kg": 2
            },
            "parcel_contents": [
                {
                    "content_number": 1,
                    "description": "Holdem Purse  (limited edition)",
                    "quantity": 1,
                    "weight_kg": 0.3,
                    "value": 67.10,
                    "country_code": "NZ"
                }
            ]
        }
    ]
}

```

Example 5: Economy Return label for a single parcel (150x100mm)

{
    "carrier": "COURIERPOST",
    "orientation": "LANDSCAPE",
    "format": "PDF",
    "sender_reference_1": "DSH-1",
    "sender_reference_2": "DSH-1",
    "paper_dimensions": {
        "width_cm": 15.0,
        "height_cm": 10.0
    },
    "label_dimensions": "150x100",
    "sender_details": {
        "name": "Nigel Mustard",
        "phone": "08001234568",
        "email": "info@hotdog.com",
        "company_name": "NZ Hotdog Company",
        "site_code": 34533
    },
    "receiver_details": {
        "name": "Donald Burger",
        "phone": "0218978569",
        "email": "nig.el@gmail.com"
    },
    "pickup_address": {
        "company_name": "ABC Limited",
        "street": "PO Box 12345",
        "suburb": "Returns Centre",
        "city": "Auckland",
        "country_code": "NZ",
        "postcode": "2154"
    },
    "delivery_address": {
        "street": "29 Stafford Street",
        "suburb": "Dunedin Central",
        "city": "Dunedin",
        "country_code": "NZ",
        "postcode": "9011"
    },
    "parcel_details": [
        {
            "service_code": "IWXEROLE",
            "return_indicator": "RETURN",
            "description": "Default",
            "currency": "NZD",
            "dimensions": {
                "length_cm": 1.0,
                "width_cm": 1.0,
                "height_cm": 1.0,
                "weight_kg": 0.376
            },
            "parcel_contents": [
                {
                    "content_number": 1,
                    "description": "Holdem Purse  (limited edition)",
                    "quantity": 1,
                    "weight_kg": 0.3,
                    "value": 67.10,
                    "country_code": "NZ"
                }
            ]
        }
    ]
}

```

Response Parameters

Sample Response

{
  "consignment_id": "DVZQYF",
  "message_id": "520f4fa0-22cc-11eb-b1e1-027414412442",
  "success": true
}